home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Extras / MIDI / camd-37.1 / development / docs / drivers.doc < prev    next >
Encoding:
Text File  |  1994-02-15  |  9.6 KB  |  202 lines
  1. How to write a hardware driver for CAMD.
  2.  
  3. CAMD drivers are fairly simple entities. Each one consists of a single
  4. load file (i.e. a file which can be loaded with LoadSeg), and lives in
  5. DEVS:midi. The "MidiPorts" preferences editor is capable of finding all
  6. of the drivers that are in that directory.
  7.  
  8. The load file for the driver begins with special sequence of code and
  9. data, similar to the RomTag structure used for disk-based libraries.
  10.  
  11.     The first thing in the driver is the instruction sequence:
  12.  
  13.         MOVEQ   #0,d0
  14.         RTS
  15.  
  16.     The prevents the driver from crashing if anybody tries to run it
  17. as an executable. Note that other instruction sequences may be subsituted,
  18. as long as they are exactly the same length.
  19.  
  20.     After the two instructions comes the MidiDeviceData structure:
  21.  
  22.         struct MidiDeviceData
  23.         {
  24.             ULONG Magic;                /* MDD_Magic */
  25.             char *Name;                 /* driver name */
  26.             char *IDString;
  27.             UWORD Version;
  28.             UWORD Revision;
  29.  
  30.             BOOL (*Init)(void);         /* called after LoadSeg() */
  31.             void (*Expunge)(void);      /* called before UnLoadSeg() */
  32.             struct MidiPortData *(*OpenPort)();
  33.             void (*ClosePort)();
  34.  
  35.             UBYTE NPorts;               /* number of ports */
  36.             UBYTE Flags;                /* currently none */
  37.         };
  38.  
  39.         #define MDD_Magic   ((ULONG)'M' << 24 | (ULONG)'D' << 16 | 'E' << 8 | 'V')
  40.  
  41.     Explanation of fields:
  42.  
  43.         Magic -- must be the character string 'MDEV'.
  44.  
  45.         Name -- pointer to the name of the driver. This should be the same as
  46.             the filename, including upper/lower case.
  47.  
  48.         IDString -- This is the "full" name of the driver. This need not be
  49.             the same as the driver file name. (For example, the driver
  50.             "checkpoint" has an IDString of "Checkpoint Serial Solution").
  51.  
  52.             NOTE: Because the driver format was created before Amiga version
  53.             strings were standardized, there is no "version string" field,
  54.             however it is suggested that each driver incorporate a version
  55.             string using the standard techniques. (Unfortunately, the driver
  56.             format cannot be radically changed because at least one music
  57.             application has been using the drivers directly long before the
  58.             CAMD library itself was finalized).
  59.  
  60.         Version, Revision -- same as for libraries.
  61.  
  62.         Init -- this is a function pointer to the initialization routine
  63.             for the driver. This routine initializes any global data
  64.             needed by the driver, finds the address of the hardware
  65.             expansion board (and determines if multiple boards are installed),
  66.             and patches the NPorts fields to indicate the number of
  67.             ports available.
  68.  
  69.             This function takes no parameters.
  70.  
  71.         Expunge -- this is a function pointer that de-allocates all global
  72.             data allocated by the Init routine.
  73.  
  74.             This function takes no parameters.
  75.  
  76.         OpenPort -- this is a pointer to a function that opens a single
  77.             hardware port and returns a pointer to a MidiPortData structure,
  78.             which is created by the driver. (Note that this structure may
  79.             be created either dynamically at the time of the call, or may
  80.             be statically allocated in the driver seglist).
  81.  
  82.             This function may also lock any hardware resources needed to
  83.                 gain exclusive access to the hardware, and may program
  84.                 interrupts and baud rates for the port.
  85.  
  86.             The function returns TRUE if the initialization succeeded,
  87.                 otherwise it returns FALSE. CAMD will expect to receive
  88.                 MIDI data at any time after this function succeeds.
  89.  
  90.             The parameters to this function are described in detail below.
  91.  
  92.         ClosePort -- this is a pointer to a function that closes a single
  93.             midi port. It may also free hardware resources if needed.
  94.  
  95.             The parameters to this function are described in detail below.
  96.  
  97. The OpenPort Function
  98. ~~~~~~~~~~~~~~~~~~~~~
  99.     This function takes the following parameters:
  100.  
  101.     register            type                explanation
  102.     ~~~~~~~~            ~~~~                ~~~~~~~~~~~
  103.         a3      struct MidiDeviceData *     pointer to MidiDeviceData
  104.         d0              LONG                port number to open
  105.         a0              (void *)()          serial transmit handler
  106.         a1              (void *)()          serial receive handler
  107.         a2              APTR                userdata for handlers
  108.  
  109.     The OpenPort call returns a pointer to the following structure in d0:
  110.  
  111.         struct MidiPortData
  112.         {
  113.                 /* function to activate transmitter interrupt when idle */
  114.  
  115.             void (*ActivateXmit)();
  116.         };
  117.  
  118.     The serial transmit handler and serial recieve handler are function
  119.     pointers to functions inside of camd.library which handle the transfer
  120.     of midi data. When CAMD calls the OpenPort function, it will supply
  121.     these pointers.
  122.  
  123.     The general scheme is that the driver should call CAMD whenever it
  124.     has recieved more data, or when it is ready to send more data. This
  125.     allows CAMD to handle the details of buffering and timestamping.
  126.  
  127.     Each function call transfers a single byte of data.
  128.  
  129.     The serial receive handler is called whenever a new byte of data is
  130.     received from the hardware. Register a2 should contain the userdata which
  131.     was passed to the OpenPort call. Register d0 should contain both the
  132.     received byte and a status code. Bits 0-7 will contain the received byte.
  133.     Bit 15 will be set if an overrun error occured, in other words, if
  134.     data was lost. Bits 8-14 should be zero. Bits higher than 15 are ignored,
  135.     and can be anything.
  136.  
  137.     The serial transmit handler should be called whenever the hardware is
  138.     ready to accept another outgoing byte. When calling this function,
  139.     register a2 should be set to the userdata which was passed to the OpenPort
  140.     call. The results will be returned in register d0 and d1. Bits 0-7
  141.     of d0 will contain the byte to be transmitted. (Bits 8-15 will
  142.     be cleared). Register d1 will be zero if CAMD has more data available
  143.     to send in it's buffer, or it will be non-zero if the buffer is empty.
  144.     In the latter case (buffer empty), the driver should send the byte in
  145.     d0 (which was the last byte remaining in the buffer), and then temporarily
  146.     suspend output processing, in other words do _not_ call the serial
  147.     transmit function again until CAMD has indicated that it has some data
  148.     in the buffer again. CAMD will do this by calling the ActivateXMit()
  149.     function using the function pointer in the MidiPortData structure.
  150.     Register A0 will contain the address of the MidiPortData structure
  151.     which was returned from OpenPort.
  152.         An example of how this works: The internal amiga serial driver
  153.     uses an interrupt for writing to the hardware. Whenever a byte is
  154.     sent out, an interrupt is generated which indicated that the hardware
  155.     is ready to accept another byte. The driver calls the serial handler
  156.     function to get the next byte from CAMD and then writes it to the
  157.     hardware. Then, it checks the "last byte" flag in d1. If the flag is
  158.     set, it disabled the interrupt. Note that the interrupt is not cleared,
  159.     merely disabled -- when the byte that was pending in the hardware
  160.     is sent out, the interrupt signal will still be generated, but it
  161.     will have no effect because it is disabled. When CAMD gets more data
  162.     to send, it calls the driver's ActivateXMit function, which re-enables
  163.     the interrupt. At this point, the interrupt which was pending goes off,
  164.     causing the driver to once again call CAMD to get another byte from it's
  165.     buffer.
  166.         Note that ActivateXMit may be called even if the driver is already
  167.     activated, i.e. the "last byte" flag was never set.
  168.  
  169. The ClosePort Function
  170. ~~~~~~~~~~~~~~~~~~~~~~
  171.     This function takes the following parameters:
  172.  
  173.     register            type                explanation
  174.     ~~~~~~~~            ~~~~                ~~~~~~~~~~~
  175.         a3      struct MidiDeviceData *     pointer to MidiDeviceData
  176.         d0              LONG                port number to close
  177.  
  178. Writing drivers for serial cards
  179. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  180.     Obviously, the CAMD driver mechanism is optimized for this type of
  181. device. Each byte is sent one at a time, and the driver need not know
  182. anything about MIDI (since it is assumed that the serial output is
  183. connected to a hardware device which is capable of parsing MIDI streams).
  184.     We have tried to make as few assumptions as possible about the
  185. interface to the hardware. In our example drivers, one has a seperate
  186. interrupt for reading and writing, while the other has a single interrupt
  187. that handles reading and writing for all ports.
  188.     In addition, in cases where the hardware provides little or no FIFO
  189. buffering, it is possible to process multiple bytes in a single interrupt
  190. by polling the hardware. This avoids the overhead of a 68000 interrupt and
  191. can increase performance and reduce overrun errors.
  192.  
  193. Writing drivers for other kinds of devices
  194. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  195.     In many cases, you will want to write a driver for a device that has no
  196. native understanding of MIDI, such as a DSP card. In this case, it is
  197. probably advisable that either the driver parse the MIDI stream itself,
  198. or place the incoming bytes into a software FIFO buffer, where they can be
  199. read and parsed by a task dedicated to that particular hardware. You can
  200. refer to the documentation file "middbasics.doc" for more information on
  201. understanding MIDI.
  202.